<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
          "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type"
        content="text/html; charset=iso-8859-1">
  <meta name="Author"
        content="David Turner">
  <title>The design of FreeType 2</title>
</head>

<body text="#000000"
      bgcolor="#FFFFFF"
      link="#0000EF"
      vlink="#51188E"
      alink="#FF0000">

<h1 align=center>
  The design of FreeType&nbsp;2
</h1>

<h3 align=center>
  Copyright&nbsp;1998-2000 David Turner (<a
  href="mailto:david@freetype.org">david@freetype.org</a>)<br>
  Copyright&nbsp;2000, 2007 The FreeType Development Team (<a
  href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>

<center>
<table width="65%">
<tr><td>

  <center>
  <table width="100%"
         border=0
         cellpadding=5>
  <tr bgcolor="#CCFFCC"
      valign=center>
    <td align=center
        width="30%">
      <a href="design-4.html">Previous</a>
    </td>
    <td align=center
        width="30%">
      <a href="index.html">Contents</a>
    </td>
    <td align=center
        width="30%">
      <a href="design-6.html">Next</a>
    </td>
  </tr>
  </table>
  </center>

  <p><hr></p>

  <table width="100%">
  <tr bgcolor="#ccccee"><td>
    <h1>
      IV. Module Classes
    </h1>
  </td></tr>
  </table>

  <p>We will now try to explain more precisely the <em>types</em> of modules
  that FreeType&nbsp;2 is capable of managing.  Note that each one of them
  is described with more details in the following chapters of this
  document.</p>

  <ul>
    <li>
      <p><em>Renderer</em> modules are used to manage scalable glyph images.
      This means <em>transforming</em> them, computing their <em>bounding
      box</em>, and <em>converting</em> them to either <em>monochrome</em>
      or <em>anti-aliased</em> bitmaps</em>.</p>

      <p>Note that FreeType&nbsp;2 is capable of dealing with <em>any</em>
      kind of glyph images, as long as a renderer module is provided for it.
      The library comes by default with two renderers:</p>

      <p><table cellpadding=8>
      <tr valign=top>
        <td>
          <tt>raster</tt>
        </td>
        <td>
          <p>Supports the conversion of vectorial outlines (described by a
          <tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>smooth</tt>
        </td>
        <td>
          <p>Supports the conversion of the same outlines to high-quality
          <em>anti-aliased</em> pixmaps (using 256 levels of gray).  Note
          that this renderer also supports direct span generation.</p>
        </td>
      </tr>
      </table></p>

    <li>
      <p><em>Font driver</em> modules are used to support one or more
      specific font format.  By default, FreeType&nbsp;2 comes with the
      following font drivers:</p>

      <p><table cellpadding=8>
      <tr valign=top>
        <td>
          <tt>truetype</tt>
        </td>
        <td>
          <p>supports TrueType font files</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>type1</tt>
        </td>
        <td>
          <p>supports Postscript Type&nbsp;1 fonts, both in binary
          (<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>) formats, including
          Multiple Master fonts.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>cid</tt>
        </td>
        <td>
          <p>supports Postscript CID-keyed fonts</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>cff</tt>
        </td>
        <td>
          <p>supports OpenType, CFF as well as CEF fonts (CEF is a
          derivative of CFF used by Adobe in its SVG viewer)</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>winfonts</tt>
        </td>
        <td>
          <p>supports Windows bitmap fonts (i.e. <tt>.fon</tt> and
          <tt>.fnt</tt>)</p>
        </td>
      </tr>
      </table></p>

      <p>Note that font drivers can support bitmapped or scalable glyph
      images.  A given font driver that supports B&eacute;zier outlines
      through <tt>FT_Outline</tt> can also provide its own hinter, or rely
      on FreeType's <tt>autohinter</tt> module.</p>
    </li>

    <li>
      <p><em>Helper</em> modules are used to hold shared code that is often
      used by several font drivers, or even other modules.  Here are the
      default helpers:</p>

      <p><table cellpadding=8>
      <tr valign=top>
        <td>
          <tt>sfnt</tt>
        </td>
        <td>
          used to support font formats based on the <tt>SFNT</tt> storage
          scheme: TrueType & OpenType fonts as well as other variants (like
          TrueType fonts that only contain embedded bitmaps)
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>psnames</tt>
        </td>
        <td>
          used to provide various useful functions related to glyph names
          ordering and Postscript encodings/charsets.  For example, this
          module is capable of automatically synthetizing a Unicode charmap
          from a Type&nbsp;1 glyph name dictionary.
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>psaux</tt>
        </td>
        <td>
          used to provide various useful functions related to Type&nbsp;1
          charstring decoding, as this "feature" is needed by the
          <tt>type1</tt>, <tt>cid</tt>, and <tt>cff</tt> drivers.
        </td>
      </tr>
      </table></p>
    </li>

    <li>
      <p>Finally, the <em>autohinter</em> module has a specific role in
      FreeType&nbsp;2, as it can be used automatically during glyph loading
      to process individual glyph outlines when a font driver doesn't
      provide its own hinting engine.</p>

      <p>This module's purpose and design is also heavily described on the
      FreeType web site.</p>
    </li>
  </ul>

  <p>We will now study how modules are described, then managed by the
  library.</p>

    <h3>
      1. The <tt>FT_Module_Class</tt> structure
    </h3>

    <p>As described later in this document, library initialization is
    performed by calling the <tt>FT_Init_FreeType()</tt> function.  The
    latter is in charge of creating a new "empty" <tt>FT_Library</tt>
    object, then register each "default" module by repeatedly calling the
    <tt>FT_Add_Module()</tt> function.</p>

    <p>Similarly, client applications can call <tt>FT_Add_Module()</tt> any
    time they wish in order to register a new module in the library.  Let us
    take a look at this function's declaration:</p>

    <font color="blue"><pre>
    extern FT_Error  FT_Add_Module(
                       FT_Library              library,
                       const FT_Module_Class*  clazz );</pre>
    </font>

    <p>As one can see, this function expects a handle to a library object,
    as well as a pointer to a <tt>FT_Module_Class</tt> structure.  It
    returns an error code.  In case of success, a new module object is
    created and added to the library.  Note by the way that the module isn't
    returned directly by the call!</p>

    <p>Here the definition of <tt>FT_Module_Class</tt>, with some
    explanation.  The following code is taken from
    <tt>&lt;freetype/ftmodule.h&gt;</tt>:</p>

    <font color="blue"><pre>
    typedef struct  FT_Module_Class_
    {
      FT_ULong               module_flags;
      FT_Int                 module_size;
      const FT_String*       module_name;
      FT_Fixed               module_version;
      FT_Fixed               module_requires;

      const void*            module_interface;

      FT_Module_Constructor  module_init;
      FT_Module_Destructor   module_done;
      FT_Module_Requester    get_interface;

    } FT_Module_Class;</pre>
    </font>

    <p>A description of its fields:</p>

    <p><table cellpadding=8>
    <tr valign=top>
      <td>
        <tt>module_flags</tt>
      </td>
      <td>
        <p>A set of bit flags used to describe the module's category.  Valid
        values are:</p>

        <ul>
          <li>
            <tt>ft_module_font_driver</tt> if the module is a font driver
          </li>
          <li>
            <tt>ft_module_renderer</tt> if the module is a renderer
          </li>
          <li>
            <tt>ft_module_hinter</tt> if the module is an auto-hinter
          </li>
          <li>
            <tt>ft_module_driver_scalable</tt> if the module is a font
            driver supporting scalable glyph formats
          </li>
          <li>
            <tt>ft_module_driver_no_outlines</tt> if the module is a font
            driver supporting scalable glyph formats that <em>cannot</em> be
            described by an <tt>FT_Outline</tt> object
          </li>
          <li>
            <tt>ft_module_driver_has_hinter</tt> if the module is a font
            driver that provides its own hinting scheme/algorithm
          </li>
        </ul>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_size</tt>
      </td>
      <td>
        <p>An integer that gives the size in <em>bytes</em> of a given
        module object.  This should <em>never</em> be less than
        <tt>sizeof(FT_ModuleRec)</tt>, but can be more if the module needs
        to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_name</tt>
      </td>
      <td>
        <p>The module's internal name, coded as a simple ASCII
        C&nbsp;string.  There can't be two modules with the same name
        registered in a given <tt>FT_Library</tt> object.  However,
        <tt>FT_Add_Module()</tt> uses the <tt>module_version</tt> field to
        detect module upgrades and perform them cleanly, even at
        run-time.</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_version</tt>
      </td>
      <td>
        <p>A 16.16 fixed float number giving the module's major and minor
        version numbers.  It is used to determine whether a module needs to
        be upgraded when calling <tt>FT_Add_Module()</tt>.</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_requires</tt>
      </td>
      <td>
        <p>A 16.16 fixed float number giving the version of FreeType&nbsp;2
        that is required to install this module.  The default value is
        0x20000 for FreeType version&nbsp; 2.0</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_interface</tt>
      </td>
      <td>
        <p>Most modules support one or more "interfaces", i.e. tables of
        function pointers.  This field is used to point to the module's main
        interface, if there is one.  It is a short-cut that prevents users
        of the module to call "get_interface()" each time they need to
        access one of the object's common entry points.</p>

        <p>Note that is is optional, and can be set to NULL.  Other
        interfaces can also be accessed through the <tt>get_interface()</tt>
        field.</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_init</tt>
      </td>
      <td>
        <p>A pointer to a function used to initialize the fields of a fresh
        new <tt>FT_Module</tt> object.  It is called <em>after</em> the
        module's base fields have been set by the library, and is generally
        used to initialize the fields of <tt>FT_ModuleRec</tt>
        subclasses.</p>

        <p>Most module classes set it to NULL to indicate that no extra
        initialization is necessary.</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>module_done</tt>
      </td>
      <td>
        <p>A pointer to a function used to finalize the fields of a given
        <tt>FT_Module</tt> object.  Note that it is called <em>before</em>
        the library unsets the module's base fields, and is generally used
        to finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>

        <p>Most module classes set it to NULL to indicate that no extra
        finalization is necessary</p>
      </td>
    </tr>
    <tr valign=top>
      <td>
        <tt>get_interface</tt>
      </td>
      <td>
        <p>A pointer to a function used to request the address of a given
        module interface.  Set it to NULL if you don't need to support
        additional interfaces but the main one.</p>
      </td>
    </tr>
    </table></p>


    <h3>
      2. The <tt>FT_Module</tt> type
    </h3>

    <p>The <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
    module object/instance, whose base structure is given by the internal
    <tt>FT_ModuleRec</tt> type.  We will intentionally <em>not</em> describe
    this structure here, as there is no point to look so far into the
    library's design.</p>

    <p>When <tt>FT_Add_Module</tt> is called, it first allocates a new
    module instance, using the <tt>module_size</tt> class field to determine
    its byte size.  The function initializes the root <tt>FT_ModuleRec</tt>
    field, then calls the class-specific initializer <tt>module_init</tt>
    when this field is not set to NULL.</p>

    <p>Note that the library defines several sub-classes of
    <tt>FT_ModuleRec</tt>, which are, as you could have guessed:</p>

    <ul>
      <li><p><tt>FT_Renderer</tt> for renderer modules</p>
      <li><p><tt>FT_Driver</tt> for font driver modules</p>
      <li><p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
    </ul>

    <p>Helper modules use the base <tt>FT_ModuleRec</tt> type.  We will
    describe these classes in the next chapters.</p>

  <p><hr></p>

  <center>
  <table width="100%"
         border=0
         cellpadding=5>
  <tr bgcolor="#CCFFCC" valign=center>
    <td align=center
        width="30%">
      <a href="design-4.html">Previous</a>
    </td>
    <td align=center
        width="30%">
      <a href="index.html">Contents</a>
    </td>
    <td align=center
        width="30%">
      <a href="design-6.html">Next</a>
    </td>
  </tr>
  </table>
  </center>

</td></tr>
</table>
</center>

</body>
</html>
